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This note clarifies MessageByName and provides examples of creating and retrieving a named 
message. 



Did You Say You Want To Get A Message? 

All you have to do is ask. Apple IlGS Toolbox Reference, Volume 3 already tells you how. 
Here's what the fine print says: with the createltFlag set to FALSE and the name of the 
message you are after in the nameString, you call MessageByName. What's unclear in the 
manual is that if the message was found, no error is returned, the createFlag is returned as 
FALSE, and messagelD contains the ID you can pass to MessageCenter to retrieve the 
contents of the message. Here's an example of MessageByName in use. 

The following code creates a named message. 

CreateNamedMessage 
pha 
pha 
pea 1 

pushlong #MsgBlock 
_Me s s ageByName 
pla 

sta myMsgID 
pla 

want 



MsgBlock dew MsgBlockEnd-MsgBlock 

dc.b 28, 'XYZ Software:My Cool Product' ; Pascal-style string 
. . . more data goes here 

MsgBlockEnd 

The following code retrieves the message. 

pha 
pha 
pea 

pushlong #MsgBlock 
_MessageByName 
ply 
pla 

bcs noMessage 



; create it 

; function $1701 

;keep the ID if you want 

; check the createFlag if you 



; don't create message 

; function $1701 
;keep id of existing message 
; createFlag (ignore) 
; carry set if an error occurred 
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below 



later 
Handle 



pea 2 
phy 

pha 
pha 
Ida #0 
pha 
pha 

Idx MylD 
phx 
pha 
pha 

pha 

_NewHandle 
Ida 3 , s 

sta mcHandle+2 
Ida l,s 
sta mcHandle 

_MessageCenter 



;MessageCenter action: GET 

;message ID for MessageCenter, 



; space for NewHandle result 
;size of handle (0) 



; ID for empty 

; handle attributes (0) 

;no special location 



;keep a copy of the handle for 

;takes Action, Msg ID, and 



Ida mcHandle+2 
pha 

Ida mcHandle 

pha 

phd 

tsc 

ted 

Idy #2 

Ida [3],y 

tax 

Ida [3] 
sta 3 
stx 5 



* now read data from the message at [3] 

Idy #$xxxx ; index past the name string 

Ida [3],y 

pld 
pla 
pla 



Ida mcHandle+2 
pha 

Ida mcHandle 
pha 

_DisposeHandle 



noMessage 

mcHandle del 
myMsgID dew 



MessageByName is available in Tool Locator versions 3.0 and later (System Software 5.0 and 
later). 



Further Reference 

• Apple IIgs Toolbox Reference, Volumes 2-3 
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